fix(agent): make publication source names and modes stable - #312

Problem

st2 agent digest/publish --spec rejects strictly valid one-Agent KDL when the source path does not end in .kdl, even though source filenames are staging details. Publication also replaces readable agent.kdl targets with the temporary file's 0600 mode.

Goal

Accept spec sources based on captured bytes and strict declaration parsing, preserve an existing declaration's accepted mode on replacement, and create new declarations with the catalog's canonical readable 0644 mode.

Decisions

• Remove the suffix gate instead of adding more accepted suffixes; the existing no-follow capture and strict one-Agent parser remain authoritative.
• Read existing bytes and mode through one no-follow file handle, then carry that mode onto the atomic replacement.
• Use 0644 for creation, matching catalog projection and declaration-authoring behavior rather than inheriting the publisher's umask or source mode.
• Leave CAS, catalog locking, control-plane staging, fsync, exact readback, bundle publication, and crash recovery unchanged.

Verification

• Public reproduction: https://github.com/schickling-repros/2026-08-st2-agent-publish-source-and-mode
  • ./repro.sh against 4629aebd1a357652a7fdbe69935bf8aae1afd67d deterministically reproduced both defects.
• Failure-capable controls:
  • arbitrary-suffix canonical input failed before the change and passes after it;
  • malformed arbitrary-suffix input remains rejected by strict parsing;
  • creation failed with mode 0600 before the change and now uses 0644 under umask 0077;
  • replacement failed with mode 0600 before the change and now preserves a distinct accepted 0640 target mode; the public repro covers the original 0644 regression.
• nix develop -c cargo test --test agent_publish spec_source_filename_is_not_semantic_after_strict_parsing -- --exact: 1 passed.
• nix develop -c cargo test --test agent_publish spec_creation_uses_the_canonical_readable_declaration_mode -- --exact: 1 passed.
• nix develop -c cargo test --test agent_publish spec_replacement_preserves_the_accepted_target_mode -- --exact: 1 passed.
• nix develop -c cargo test --workspace --lib --bins: 369 passed.
• nix develop -c cargo fmt --all -- --check: passed.
• nix build .#default: passed.
• git range-diff reports the pre-restack and post-restack publication commits as patch-identical.

Exact verified base: e282a7e732217fd3f5cfaa60095b558b248d2ca7.

Exact verified head: 1a8f4009b4c9a85e37cdb035463959494ede8628.

Complexity

No new public abstraction. One private value binds existing declaration bytes and mode captured from the same no-follow file handle.

Concerns

Replacement intentionally preserves the accepted target's complete permission bits. Creation always normalizes to 0644; source-file permissions remain non-semantic.

Friction & bottlenecks

• Friction: running the workspace and Nix process-control tests concurrently produced three unrelated transient failures. Each named test passed alone, and both complete gates passed when rerun sequentially.
• Bottlenecks: none observed.

Follow-ups

None.

References

Closes #155.

Closes #311.

Former prerequisites #307 and #313 are merged in the exact base.

Downstream tracking: https://github.com/schickling/dotfiles/pull/1902